Linux webm002.cluster126.gra.hosting.ovh.net 5.15.206-ovh-vps-grsec-zfs-classid #1 SMP Fri May 15 02:41:25 UTC 2026 x86_64
/
home
/
ariannadhf
/
www
/
wp-content
/
plugins
/
themeisle-companion
/
/home/ariannadhf/www/wp-content/plugins/themeisle-companion/CONTRIBUTING.md
# Contributing Thank you for thinking about contributing to Orbit Fox! All sorts of contributions are welcomed. ## License Orbit Fox is [licensed under the GPLv2+](LICENSE.txt), and all contributions to Orbit Fox will be released under the GPLv2+ license. By contributing to this repository, you agree to release your contribution under the GPLv2+ license. ## Setting Up Local Environment You need a WordPress Environment to run the plugin on. This project needs a lot of different packages to be installed before you can start coding, but we've made the process easier with Docker. ### Getting Started with Docker The quickest way to get up and running is to use the provided [Docker](https://www.docker.com/) setup which takes care of setting up the environment for you within seconds. Install docker and docker-compose by following the most recent instructions on the Docker site. Once Docker is installed, fork Orbit Fox repository. Clone your fork of this project and enter the working directory: ``` git clone http://github.com/YOUR-USERNAME/themeisle-companion/ cd themeisle-companion ``` Once inside the folder, you can run the following command to start your Docker container: ``` docker-compose up -d ``` This will make your WordPress instance up and running at http://localhost:8888 - If you want to use a different port for your environment, then you can change it from [docker-compose.yml](docker-compose.yml) file. - If you're developing themes, or core WordPress functionality alongside Orbit Fox, you can make the WordPress files accessible in `/themeisle-companion/wordpress/` folder in your home directory. - If you want bash access to your environment, you can use the following command to find the ID of your Docker container: ``` docker ps ``` And then you can get bash access with the following command: ``` docker exec -it <ID OF YOUR CONTAINER> bash ``` If you want to stop your Docker container, for the time being, you can use the following command: ``` docker-compose stop ``` Moreover, if you want to delete your Docker instance, you can use: ``` docker-compose down ``` ### Installing Dependencies Once you've bash access of your WordPress container, you need to enter your Orbit Fox directory with: ``` cd /var/www/html/wp-content/plugins/themeisle-companion/ ``` Now, we need to install `npm` and `composer` dependencies with the following commands: ``` npm install composer install ``` Now you can start making your changes to the plugin. ### Running Grunt Tasks We use [Grunt](https://gruntjs.com/) for automating many tasks, such as compiling Sass to CSS, PHP Code Sniffer, and more. Once you have made your changes, you can run Grunt tasks by running: ``` grunt local ``` It will take some time to finish all the tasks. If there are any issues found in PHP or JavaScript, it gives you a detailed log inside `/logs/` folder of the plugin. Fix those issues and run `grunt local` again until it finishes without an error. ### PHP_CodeSniffer To run PHP_CodeSniffer, run `composer lint`. This will run the WordPress Coding Standards checks. To fix automatically fixable issues, run `composer format`. ### PHP Unit Testing Tests for PHP use PHPUnit as the testing framework, which is run with: ``` phpunit ``` ## Coding Standards Code must follow [WordPress Coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/), which is checked when running tests (more on this below). ## Security and Sanitization When [outputting data](https://developer.wordpress.org/plugins/security/securing-output/), escape it using WordPress' escaping functions such as `esc_html()`, `esc_attr__()`, `wp_kses()`, `wp_kses_post()`. When reading [user input](https://developer.wordpress.org/plugins/security/securing-input/), sanitize it using WordPress' sanitization functions such as `sanitize_text_field()`, `sanitize_textarea_field()`. When writing to the database, prepare database queries using ``$wpdb->prepare()`` Never trust user input. Sanitize it. Make use of [WordPress nonces](https://codex.wordpress.org/WordPress_Nonces) for saving form submitted data. Coding standards will catch any sanitization, escaping or database queries that aren't prepared. ## Types of Test There are different types of tests that can be written: - Acceptance Tests: Test as a non-technical user in the web browser. - Functional Tests: Test the framework (WordPress). - Integration Tests: Test code modules in the context of a WordPress website. - Unit Tests: Test single PHP classes or functions in isolation. - WordPress Unit Tests: Test single PHP classes or functions in isolation, with WordPress functions and classes loaded. There is no definitive / hard guide, as a test can typically overlap into different types (such as Acceptance and Functional). The most important thing is that you have a test for *something*. If in doubt, an Acceptance Test will suffice. ### Writing an Acceptance Test An acceptance test is a test that simulates a user interacting with the Plugin or Theme in a web browser. Refer to Writing an End-to-End Test below. ### Writing an End-to-End Test To write an End-to-End test, create a new file under `e2e-tests/specs` with the name of the spec or functionality you are testing, and add `.spec.test` to the file name. E.g. for `e2e-tests/specs/checkout.spec.test.js`, the test file should be `checkout.spec.test.js`. For more information on writing End-to-End tests, refer to the [Playwright documentation](https://playwright.dev/docs/test-intro). You can check End-to-End [README](./e2e-tests/README.md) for more details. ## Writing a WordPress Unit Test WordPress Unit tests provide testing of Plugin/Theme specific functions and/or classes, typically to assert that they perform as expected by a developer. This is primarily useful for testing our API class, and confirming that any Plugin registered filters return the correct data. To create a new WordPress Unit Test, create a new file under `tests/php/unit` with the name of the class you are testing, and the suffix `Test`. The filename should be in `lower-case-with-dash`, and the class name should be in `CamelCase`. E.g. for `tests/php/unit/class-api-test.php`, the test class should be `class APITest extends \PHPUnit\Framework\TestCase`. ```php <?php class APITest extends \PHPUnit\Framework\TestCase { /** * @var \WpunitTester */ protected $tester; public function setUp(): void { // Before... parent::setUp(); // Your set up methods here. } public function tearDown(): void { // Your tear down methods here. // Then... parent::tearDown(); } // Tests public function test_it_works() { $post = static::factory()->post->create_and_get(); $this->assertInstanceOf(\WP_Post::class, $post); } } ``` ## Run PHPUnit Tests Once you have written your code and test(s), run the tests to make sure there are no errors. ```bash ./vendor/bin/phpunit tests/php/unit/class-api-test.php ``` Any errors should be corrected by making applicable code or test changes. ## Run PHP CodeSniffer In the Plugin's or Theme's directory, run the following command to run PHP_CodeSniffer, which will check the code meets Coding Standards as defined in the `phpcs.tests.xml` configuration: ```bash composer run lint ``` `--standard=phpcs.tests.xml` tells PHP CodeSniffer to use the Coding Standards rules / configuration defined in `phpcs.tests.xml`. These differ slightly from WordPress' Coding Standards, to ensure that writing tests isn't a laborious task, whilst maintain consistency in test coding style. `-v` produces verbose output `-s` specifies the precise rule that failed Any errors should be corrected by either: - making applicable code changes - running `composer run format` to automatically fix coding standards Need to change the PHP or WordPress coding standard rules applied? Either: - ignore a rule in the affected code, by adding `phpcs:ignore {rule}`, where {rule} is the given rule that failed in the above output. - edit the [phpcs.tests.xml](phpcs.tests.xml) file. ## Sending a Pull Request A good workflow for pull requests to follow is listed below: - Fork Orbit Fox repository - Clone forked repository - Use **development** branch for your changes, or create a new branch from **development** branch. - Setup environment - Make code changes - Run Grunt tasks and PHPUnit tests. - Push branch to forked repository - Submit Pull Request ## Reporting Security Issues ThemeIsle team takes security bugs very seriously. Do not report potential security vulnerabilities here. Email them privately to our team at friends@themeisle.com ## Reporting a Bug We use [GitHub issues](https://github.com/Codeinwp/themeisle-companion/issues) for tracking bugs. When filing an issue, make sure to answer these questions: - What version of Orbit Fox are you using? - What version of WordPress are you using are you using? - What did you do? - What did you expect to see? - What did you see instead? Explain the problem and include additional details to help maintainers reproduce the problem: - Use a clear and descriptive title for the issue to identify the problem. - Describe the exact steps which reproduce the problem in as many details as possible, including screenshots if needed. ## Localizing Orbit Fox Plugin You don't need to be a developer to contribute to Orbit Fox. You can also contribute to the project by translating it to your language. You can find your [locale here](https://translate.wordpress.org/projects/wp-plugins/themeisle-companion). Language packs are automatically generated once 95% of the plugin's strings are translated and approved for a locale.